COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	@Part(Intro, Root = "CLM.MSS")
C00037 ENDMK
C⊗;
@Part(Intro, Root = "CLM.MSS")
λ↓ Comment{Chapter of Common Lisp Manual.  (c) 1982 Guy L. Steele Jr.}

@MyChapter[Introduction]

This manual documents a dialect of @xlisp called ``@clisp@;'', which is a
successor to @maclisp @Cite(MOONUAL), influenced strongly by @lmlisp
@Cite(BLUE-LISPM) and also to some extent by @scheme
@Cite(SCHEME-REVISED-REPORT) and @interlisp @Cite(INTERLISP).

@Section[Purpose]

@clisp is intended to meet these goals:
@Begin[Description]
@i[Commonality].@\@clisp originated in an attempt to focus the work
of several implementation groups each of which was constructing successor
implementations of @maclisp for different computers.  These
implementations had begun to diverge because of the differences in the
implementation environments: microcoded personal computers (@lmlisp,
@slisp), commercial timeshared computers (@newlisp), and supercomputers
(@s1lisp).  While the differences among the several implementation
environments will of necessity force incompatibilities among the
implementations, nevertheless @clisp can serve as a common dialect of
which each implementation can be an upward-compatible superset.

@i[Portability].@\@clisp intentionally excludes features
that cannot easily be implemented on a broad class of machines.
On the one hand, features that are difficult or expensive
to implement on hardware without special microcode are avoided
or provided in a more abstract and efficiently implementable form.
(Examples of this are the forwarding (invisible) pointers
and locatives of @lmlisp.  Some of the problems that they solve
are addressed in different ways in @clisp.)
On the other hand, features that are useful only on certain ``ordinary''
or ``commercial'' processors are avoided or made optional.  (An example of
this is the type declaration facility, which is useful in some
implementations and completely ignored in others; type declarations are
completely optional and for correct programs
affect only efficiency, never semantics.)
Moreover, attention has been paid to making it easy to write programs in
such a way as to depend as little as possible on machine-specific
characteristics such as word length, while allowing some variety of
implementation techniques.

@i[Consistency].@\Most @xlisp implementations are internally inconsistent
in that by default the interpreter and compiler may assign @i[different]
semantics to correct programs; this stems primarily from the fact
that the interpreter assumes all variables to be dynamically scoped,
while the compiler assumes all variables to be local unless forced
to assume otherwise.  This has been done for the sake of convenience
and efficiency, but can lead to very subtle bugs.  The definition of
@clisp avoids such anomalies by explicitly requiring the interpreter
and compiler to impose identical semantics on correct programs.

@i[Power].@\@clisp is a descendant of @maclisp, which has always
placed emphasis on providing system-building tools.
Such tools may in turn be used to build the user-level packages
such as @interlisp provides; these packages are not, however, part
of the @clisp core specification.  It is expected such packages will
be built on top of the @clisp core.

@Begin[Multiple]
@i[Expressiveness].@\@clisp culls not only from @maclisp but from
@interlisp, other @xlisp dialects, and other programming languages
what we believe from
experience to be the most useful and understandable constructs.
Constructs that have proved to be awkward or less useful are being
eliminated (an example is the @f[store] construct of @maclisp).
@End[Multiple]

@i[Compatibility].@\Unless there is a good reason to the contrary,
@clisp strives to be compatible with @lmlisp, @maclisp, and
@interlisp, roughly in that order.

@i[Efficiency].@\@clisp has a number of features designed to
facilitate the production of high-quality compiled code in those
implementations that care to invest effort in an optimizing compiler.
One implementation of @clisp (namely @s1lisp) already has a compiler
that produces code for numerical computations that is competitive
in execution speed to that produced by a @fortran compiler @Cite(S1-COMPILER).
(This extends the work done in @maclisp to produce extremely efficient
numerical code @Cite(MACLISP-BEATS-FORTRAN).)

@i[Stability].@\It is intended that @clisp, once defined and agreed upon,
will change only slowly and with due deliberation.  The various dialects
that are supersets of @clisp may serve as laboratories within which to
test language extensions, but such extensions will be added to
@clisp only after careful examination and experimentation.
@End[Description]

The @clisp documentation is divided into four parts,
known for now as the white pages, the yellow pages, the red pages,
and the blue pages.  (This document is the white pages.)
@begin[itemize]
The @i[white pages] (this document) is a language specification
rather than an implementation specification.  It defines a set of
standard language concepts and constructs that may be used
for communication of data structures and algorithms in the @clisp
dialect.  This is sometimes referred to as the ``core @clisp language'',
because it contains conceptually necessary or important features.
It is not necessarily implementationally minimal.
While some features could be defined in terms of others
by writing @xlisp code (and indeed may be implemented that way),
it was felt that these features should be conceptually primitive
so that there might be agreement among all users as to their usage.
(For example, bignums and ratinumbers could be implemented as
@xlisp code given operations on fixnums.  However, it is important
to the conceptual integrity of the language that they be regarded
by the user as primitive, and they are useful enough to warrant
a standard definition.)

The @i[yellow pages] is a program library document, containing
documentation for assorted and relatively independent packages of code.
While the white pages are to be relatively stable, the yellow pages are
extensible; new programs of sufficient usefulness and quality will
routinely be added from time to time.  The primary advantage of the
division into white and yellow pages is this relative stability;
a package written solely in the white-pages language should not break
if changes are made to the yellow-pages library.

The @i[red pages] is implementation-dependent documentation;
there will be one set for each implementation.  Here are specified
such implementation-dependent parameters as word size, maximum
array size, sizes of floating-point exponents and fractions, and so on,
as well as implementation-dependent functions such as input/output
primitives.

The @i[blue pages] constitutes an implementation guide
in the spirit of the @interlisp virtual machine specification
@Cite(INTERLISP-VM).  It specifies a subset of the white pages
that an implementor must construct, and indicates a quantity of @xlisp
code written in that subset that implements the remainder of the white
pages.  In principle there could be more than one set of blue pages, each
with a companion file of @xlisp code.  (For example, one might assume
@f[if] to be primitive and define @f[cond] as a macro in terms of @f[if],
while another might do it the other way around.)
@end[itemize]

@Section[Notational Conventions]

In @clisp, as in most @xlisp dialects, the symbol @Varref[nil]
is used to represent both the empty list and the ``false'' value
for Boolean tests.  An empty list may, of course, also be written
``@f[()]''; this normally denotes the same object as ``@f[nil]''.
(It is possible, by extremely perverse manipulation of the package system,
to cause the sequence of letters ``@f[nil]'' to be recognized
not as the symbol that represents the empty list but as another
symbol with the same name.  However, ``@f[()]'' @i[always] denotes
the empty list.  This obscure possibility will be ignored in this document.)
These two notations may be used interchangeably as far as the @xlisp
system is concerned.  However, as a matter of style,
this document
will prefer the notation ``@empty@;'' when it is desirable to emphasize
its use as an empty list, and will prefer the notation ``@false@;''
when it is desirable to emphasize its use as the Boolean ``false''
or as a symbol.  Moreover, an explicit quote mark is used to emphasize
its use as a symbol rather than as Boolean ``false''.
@Lispx
@tabdivide(2)
(append '@empty '@empty) @EV @empty@\;@r[Emphasize use of empty lists.]
(not @false) @EV @true@\;@r[Emphasize use as Boolean ``false''.]
(get '@nil 'color)@\;@r[Emphasize use as a symbol.]
@Endlisp

Any data object other than @false is construed to be Boolean
``not false'', that is, ``true''.  The symbol @true is conventionally
used to mean ``true'' when no other value is more appropriate.
When a function is said to ``return @i[false]'' or to ``be @i[false]''
in some circumstance, this means that it returns @false.
However, when a function is said to ``return @i[true]'' or to ``be @i[true]''
in some circumstance, this means that it returns some value other
than @false, but not necessarily @true.

All numbers in this document are in decimal notation unless
there is an explicit indication to the contrary.

Execution of code in @xlisp is called @i[evaluation], because executing a
piece of code normally results in a data object called the @i[value]
produced by the code.  The symbol ``@EV'' will be used in examples to
indicate evaluation.
For example:
@Lisp
(+ 4 5) @EV 9
@Endlisp
means ``the result of evaluating the code @f[(+ 4 5)] is (or would be,
or would have been) @f[9]''. 

The symbol ``@EX'' will be used in examples to indicate macro expansion.
For example:
@Lisp
(push x v) @EX (setf v (cons x v))
@Endlisp
means ``the result of expanding the macro-call form @f[(push x v)]
is @f[(setf v (cons x v))]''.  This implies that the two pieces
of code do the same thing; the second piece of code is
the definition of what the first does.

The symbol ``@EQ'' will be used in examples to indicate code equivalence.
For example:
@Lisp
(- x y) @EQ (+ x (- y))
@Endlisp
means ``the value and effects of @f[(- x y)] is always the same as the value
and effects of
@f[(+ x (- y))] for any values of the variables @f[x] and @f[y]''.
This implies that the two pieces
of code do the same thing; however, neither directly defines
the other in the way macro-expansion does.

When this document specifies that it ``is an error'' for some situation
to occur, this means that:
@Begin[Itemize]
No valid @clisp program should cause this situation to occur.

If this situation occurs, the effects and results are completely
undefined as far as adherence to the @clisp specification is concerned.

No @clisp implementation is required to detect such an error.
@End[Itemize]
This is not to say that some particular implementation might not define
the effects and results for such a situation; it is merely that no program
conforming to the @clisp specification may correctly depend on such
effects or results.

On the other hand, if it is specified in this document that in some situation
``an error is @i[signalled]'', this means that:
@Begin[Itemize]
If this situation occurs, an error (see @Funref[error]) will be signalled.

Valid @clisp programs may rely on the fact that an error will be signalled.

Every @clisp implementation is required to detect such an error.
@End[Itemize]

@Begin(Table)
@Mline()
@Defun[Fun {sample-function}, Args {@i[arg1] @i[arg2] @optional @i[arg3] @i[arg4]}]
The function @f[sample-function] adds together @i[arg1] and @i[arg2], and
then multiplies the result by @i[arg3].  If @i[arg3] is not provided or
is @nil, the multiplication isn't done.  @f[sample-function] then returns
a list whose first element is this result and whose second element is
@i[arg4] (which defaults to the symbol @f[foo]).
@Lispx
(function-name 3 4) @EV (7 foo)
(function-name 1 2 2 'bar) @EV (6 bar)
@Endlisp
As a rule,
@f[(sample-function @i[x] @i[y])] @EQ @f[(list (+ @i[x] @i[y]) 'foo)].
@Enddefun
@Caption(Sample Function Description)
@Tag(Sample-Function-Description)
@Mline()
@Defvar[Var {sample-variable}]
The variable @f[sample-variable] specifies how many times
the special form @f[sample-special-form] should iterate.
The value should always be a non-negative integer or @nil
(which means iterate indefinitely many times).  The initial value is @f[0].
@Enddefvar
@Caption(Sample Variable Description)
@Tag(Sample-Variable-Description)
@Mline()
@Defcon[Var {sample-constant}]
The named constant @f[sample-constant] has as its value
the height of the terminal screen in furlongs times
the base-2 logarithm of the implementation's total disk capacity in bytes,
as a floating-point number.
@Enddefcon
@Caption(Sample Constant Description)
@Tag(Sample-Constant-Description)
@Mline()
@End(Table)

Functions, variables, named constants, special forms, and macros are described
using a distinctive typographical format.
Table @Ref(Sample-Function-Description) illustrates the manner
in which @clisp functions are documented.
The first line specifies the name of the function,
the manner in which it accepts arguments,
and the fact that it is a function.  Following indented paragraphs
explain the definition and uses of the function and often
present examples or related functions.

In general, actual code (including actual names of functions)
appears in this typeface: @f[(cons a b)].
Names that stand for pieces of code (meta-variables) are written in
@i[italics].  In a function description, the names of the parameters appear
in italics for expository purposes.  The word ``@f[&optional]'' in the
list of parameters indicates that all arguments past that point are
optional; the default values for the parameters are described in the
text.  Parameter lists may also contain ``@rest@;'', indicating that an
indefinite number of arguments may appear, or ``@key@;'', indicating
that keyword arguments are accepted.
(The @optional/@rest/@key
syntax is actually used in @clisp function definitions for these purposes.)

Table @Ref(Sample-Variable-Description) illustrates the manner in
which a global variable is documented.  The first line specifies the
name of the variable and the fact that it is a variable.

Table @Ref(Sample-Constant-Description) illustrates the manner in
which a named constant is documented.  The first line specifies the
name of the constant and the fact that it is a constant.
(A constant is just like a global variable, except that it is
an error ever to alter its value or to bind it to a new value.)

@begin(Table)
@mline()
@Defspec[Fun {sample-special-form}, Args {@Mopt<@i[name]> (@Mstar<@i[var]>) @Mplus<@i[form]>}]
This evaluates each form in sequence as an implicit @f[progn], and does this
as many times as specified by
the global variable @f[sample-variable].  Each variable @i[var] is bound
and initialized to @f[43] before the first iteration, and unbound after
the last iteration.
The name @i[name], if supplied, may be used in a @Funref[return-from] form
to exit from the loop prematurely.  If the loop ends normally,
@f[sample-special-form] returns @nil.
@Lispx
(setq sample-variable 3)
(sample-special-form @empty @i[form1] @i[form2])
@Endlisp
This evaluates @i[form1], @i[form2], @i[form1], @i[form2], @i[form1], @i[form2]
in that order.
@Enddefspec
@Caption(Sample Special Form Description)
@Tag(Sample-Special-Form-Description)
@mline()
@Defmac[Fun {sample-macro}, Args {@i[var] @Mstar<@i[tag] @mor @i[statement]>}]
This evaluates the statements as a @f[prog] body,
with the variable @i[var] bound to @f[43].
@Lisp
(sample-macro x (+ x x)) @EV 86
(sample-macro @i[var] . @i[body]) @EX (prog ((@i[var] 43)) . @i[body])
@Endlisp
@Enddefmac
@Caption(Sample Macro Description)
@Tag(Sample-Macro-Description)
@Mline()
@End(Table)

Tables @Ref(Sample-Special-Form-Description)
and @Ref(Sample-Macro-Description) illustrate the documentation
of special forms and macros (which are closely related in purpose).
These are very different from functions.
Functions are called according to a single,specific, consistent syntax;
the @optional/@rest/@key syntax specifies how the function uses its arguments
internally, but does not affect the syntax of a call.
In contrast, each special form or macro can have its own idiosyncratic syntax.
It is by special forms and macros that the syntax of @clisp is defined
and extended.

In the description of a special form or macro, an italicized word names a
corresponding part of the form that invokes the special form or macro.
Parentheses (``@f[(]'' and ``@f[)]'') stand for themselves, and should be
written as such when invoking the special form or macro.
Brackets, braces, stars, plus signs, and vertical bars are metasyntactic
marks.
Square brackets
(``['' and ``]'') indicate that what they enclose is optional
(may appear zero times or one time in that place); the square
brackets should not be written in code.
Curly braces (``{'' and ``}'') simply parenthesize what they enclose,
but may be followed by a star (``*'') or a plus sign (``+'');
a star indicates that what the braces enclose may appear any number of times
(including zero, that is, not at all), while a plus sign indicates
that what the braces enclose may appear any non-zero number of times
(that is, must appear at least once).  Within braces or brackets,
vertical bars (``|'') separate mutually exclusive choices.
In summary, the notation ``@Mstar<@i[x]>'' means zero or more occurrences
of ``x'', the notation ``@Mplus<@i[x]>'' means one or more occurrences
of ``x'', and the notation ``@mopt<@i[x]>'' means zero or one occurrences
of ``x''.  These notations are also used for syntactic
descriptions expressed as @c[bnf]-like productions, for example
in Table @Ref(NUMBER-SYNTAX-TABLE).

In the last example in Table @Ref(Sample-Macro-Description), notice the
use of ``dot notation''.  The ``@f[.]''  appearing in the expression
@f[(sample-macro @i[var] . @i[body])] means that the name @i[body] stands
for a list of forms, not just a single form, at the end of a list.  This
notation is often used in examples.
@Blankspace(2 lines)

The term ``@xLisp reader'' refers not to you, the reader of this document,
nor to some person reading @xlisp code, but specifically
to a @xlisp program (the function @Funref[read])
that reads characters from an input stream and interprets them by parsing
as representations of @xlisp objects.

Certain characters are used in special ways in the syntax of @clisp.
The complete syntax is explained in detail in Chapter @Ref(IO),
but a quick summary here may be useful:
@Begin(DenseDescription, Leftmargin +.3 in, Indent -.3 in)
@f[']@\An accent acute (``single quote'') followed by an expression @i[form]
is an abbreviation for @f[(quote @i[form])].  Thus @f['foo] means
@f[(quote foo)] and @f['(cons 'a 'b)] means @f[(quote (cons (quote a) (quote b)))].

@f[;]@\Semicolon is the comment character.  It and all characters up to the
end of the line are discarded.

@f["]@\Double quotes surround character strings:
@f["This is a thirty-nine character string."].

@f[\]@\Backslash is an escape character.  As a rule, it causes the
next character to be treated as a letter rather than for its usual
syntactic purpose.  For example, @f[A\(B] denotes a symbol whose name is
``@f[A(B]'', and @f["\""] denotes a character string containing one character,
a double-quote.

@f[#]@\The number sign begins a more complex syntax.
The next character designates the precise syntax to follow.
For example, @f[#o105] means 105@-[8] (105 in octal notation);
@f[#\L] denotes a character object for the character ``@f[L]''; and
@f[#(a b c)] denotes a vector of three elements @f[a], @f[b], and @f[c].
A particularly important case is that @f[#'@i[fn]] means @f[(function @i[fn])],
in a manner analogous to @f['@i[form]] meaning @f[(quote @i[form])].

@f[|]@\Vertical bars surround the name of a symbol that has
special characters in it.

@f[`]@\Accent grave (``backquote'') signals that the next expression
is a template that may contain commas.  The backquote syntax
represents a program that will construct a data structure
according to the template.

@f[,]@\Commas are used within the backquote syntax.

@f[:]@\Colon is used to indicate which package a symbol belongs to.
For example, @f[chaos:reset] denotes the symbol named @f[reset]
in the package named @f[chaos].  A leading colon indicates a @i[keyword],
a symbol that always evaluates to itself.
@End(DenseDescription)

All code in this manual is written in lower case.
@clisp is generally insensitive to the case in which code
is written.  Internally, names of symbols are ordinarily
converted to and stored in upper-case form.
There are ways to force case conversion on output if desired.
In this document, wherever an interactive exchange between a user
and the @xlisp system is shown, the input is exhibited in lower case
and the output in upper case.

Some symbols are written with the colon (@f[:])
character apparently in their names.  In particular, all @i[keyword] symbols
have names starting with a colon.  The colon
character is not actually part of the print name, but is a package
prefix indicating that the symbol belongs to the keyword package.
This is all explained in Chapter @Ref(PACKAG); until you read
that, just make believe that the colons are part of the names of the
symbols.